A Guide To ‘accessrmd’.
Richard Leyshon
25 July 2021
Introduction
At A Glance
{accessrmd} is currently in development. If you discover bugs or improvements, please review the code of conduct and contribute on GitHub.
{accessrmd} is a package written to help improve the accessibility of Rmarkdown documents. The standard Rmarkdown outputs have HTML structural issues that result in problems for people using screen readers. The purpose of {accessrmd} is to help developers in writing accessible Rmarkdown documents and in converting a back catalogue of documents in need of accessibility amendments.
{accessrmd} is currently limited to html_output only. It is not available on CRAN yet, but this is the aim once the first release has been published.
To install the development version:
devtools::install_github("datasciencecampus/accessrmd")To attach the package:
library(accessrmd)What problem does it solve?
The HTML structure of standard rmarkdown outputs are not AA WCAG2.1 standard. AA is the standard required by all UK government digital services. In order to present HTML checks, I will be enlisting the help of the excellent, open-source WAVE accessibility tool. It doesn’t catch everything required for AA-compliance, but it’s a great way to get started with an accessibility audit, including helpful explanations for newcomers to WCAG 2.1 compliance.
The below image shows the output of a WAVE check on the standard Rmarkdown html output. As you can see, there are a number of errors and warnings. Click the image for more detail.
Click the image to view the full check on wave.webaim.org, opens in new window.
By executing a few functions from the {accessrmd} package, the html format issues can be easily remedied, without the developer needing to write any HTML. Please observe the output of an Rmarkdown which has been adjusted by {accessrmd} functions (again, you can click for an interactive check):
Click the image to view the full check on wave.webaim.org, opens in new window.
Functions Gallery
In this section, I will be working with a test Rmarkdown document. It contains a simple ggplot chart and a test image. Click to see the test Rmarkdown output.
Click to see the WAVE check. Note the errors and warnings.
The issues are caused by the HTML structure and YAML settings. The YAML currently looks like this:
lines <- readLines("test.Rmd")
# Show only the YAML
message(paste(lines[1:6], collapse = "\n"))---
title: "Test"
author: "Richard Leyshon"
date: "25/07/2021"
output: html_document
---access_head()
Reads an Rmd file, converting the YAML header to a format that is screen-reader friendly.
Most of the issues with the test Rmarkdown can be fixed with this single function. We just need to call it and specify a few parameters:
rmd_pathis the relative path to the Rmarkdown.lanvalue will be used to set the HTML lang attribute value. I’ll specify “en” for English.inplace = FALSE(the default) will ensure the original Rmd doesn’t get overwritten.
access_head(rmd_path = "test.rmd", lan = "en")Setting html lan to enaccess_head() created an accessrmd directory with an adjusted rmd.
list.files("accessrmd", full.names = TRUE)[1] "accessrmd/corrected_images.html" "accessrmd/corrected_images.rmd" "accessrmd/images.html"
[4] "accessrmd/images.rmd" "accessrmd/test.html" "accessrmd/test.rmd" Click to view the output HTML.
Click to view the WAVE report.
This function has resolved the following issues:
- Language missing or invalid
- No page regions
- Skipped heading level
The remaining errors or warnings are related to the chart and image. We can also view the file lines to see how the file was modified.
lines <- readLines("accessrmd/test.rmd")
# Show only the head
message(paste(lines[1:7], collapse = "\n"))<html lang="en">
<header>
<title>Test</title>
<h1 id="title toc-ignore">Test</h1>
<h2 class="header_h2s">RichardLeyshon</h2>
<h2 class="header_h2s">25/07/2021</h2>
</header>access_img()
Reads in an image and produces the HTML structure expected by web accessibility checkers such as WAVE. Also works as a wrapper around {ggplot2} charts.
This function can be used to resolve the remaining issues in the Rmarkdown. Inserting access_img() will resolve the chart issue, as it works with ggplot2::last_plot().
For images using markdown syntax, replacing the markdown with access_img() will ensure the image is renderred with the expected alt text value. This is important as markdown syntax  renders unreliably, causing issues with duplicated alt text warnings on WAVE.
# store the correct code lines as length 1 character vectors
# chart code specifying alt text
chart <- 'access_img(alt = "Plot of pressure vs temperature.")'
# test image code, specifying alt text and dimensions
img <- as.character(
'`r access_img(img = "../www/then-and-now-carole-hersee.jpeg",
alt = "BBC Test card then and now.", wid = 800, ht = 450)`')
# read in the rmd lines
lines <- readLines("accessrmd/images.rmd")
# Replace the blank line following ggplot code with access_img
lines[32] <- chart
# Replace the inaccessible markdown image with inline r code.
lines[37] <- img
# create a new file
file.create("accessrmd/corrected_images.rmd")
# write the modified lines
writeLines(lines, "accessrmd/corrected_images.rmd")
# render the markdown
rmarkdown::render("accessrmd/corrected_images.rmd")
processing file: corrected_images.rmdimg derived from disk.output file: corrected_images.knit.md
Output created: corrected_images.htmlClick to view the output html.
check_alt_len()
In development.
detect_html_lang()
In development.
find_all_alts()
In development.
find_all_imgs()
Not exported. Find any markdown or HTML syntax images within read lines. Check any lines for images and return the line numbers and values.
handle_rmd_path()
Not exported. Helper function.Checks rmd_path exists and that the file type is as expected.
sus_alt()
Suspicious alt text - checks if an image’s alt text is equal to alt attribute placeholder values, including ‘nbsp’, ‘spacer’ and the src attribute value (filename).
Github Actions
A continuous deployment workflow has been employed in the development of {accessrmd}, using GitHub Actions.
This workflow has allowed efficient adaptation of the package modules while ensuring the integrity of the outputs and conditional behaviours.
CD workflows for this package include:
- CRAN build checks.
- Test coverage with Codecov.
- Automated linting.
R CMD Build Check
An automated test suite analagous to the checks run by CRAN on package submission.
This suite of checks is something that I tend to execute as part of my development practice. However, setting automated checks on push to the remote ensures that human error is mitigated. Collaborators or developers wishing to install the development version of {accessrmd} can be informed of the current state of the repository and assured of the package’s functionality.
As can be seen from the screenshot below, the package is tested for compatibility with three different operating systems, Windows, MacOS and 2 flavours of Ubuntu.
Clicking on an item in the check manifest allows you to view the detailed check schedule. If any checks failed, you can consult the log to help pinpoint the error.
Test Coverage With Codecov
Codecov test coverage
I utilise Test-Driven Development when writing software in order to mitigate against misuse cases.
@tired_actor ##duet with @brock1137 no please no ##funny ##Welcome2021 ##2021 ##newyear ##firstpost ##viral ##fyp ##foryou ##foryoupage ##comedy ##crying ##2020 ##RareAesthetic
♬ The Square Hole - Brock
All jokes to the side, ensuring that your functions are safe is vital. This helps mitigate against poor documentation and misinterpretation.
Code coverage gives an indication of the percentage of code lines that are exercised when the test battery is run. However, I would advise caution in assuming that a high coverage equates to quality software. It tends to be very easy to write a suite of tests that result in high coverage. This does not mean that all necessary exception handling has been considered and tested.
Thorough and well-considered test conditions are excellent tools in assuring quality software. It also means that you can turn your failures into future successes - every bug you encounter can be converted to a meaningful test.
Below, you can view the test coverage workflow on pushing to the remote.
Linting
Automated linting using the {lintr} package with GitHub actions is used to help ensure code adheres to the tidyverse style guide. Code readability is important in assisting collaboration. Data Science Campus guidance is to apply the tidyverse style guide.
Perhaps more important than the adopted style is to ensure that code is conscientiously commented. Your colleagues and future self will value the effort taken in explaining your code.
More Projects By The Author
GitHub Projects
‘ptspotter’ Package
‘ptspotter’ is a package that aims to simplify some of the mundane tasks involved in setting up an analytical pipeline using the fantastic ProjectTemplate framework.
ptspotter is available on CRAN.
Highways England Traffic Data
This data pipeline was redeveloped in December 2020 as Brexit approached. It has been an important source of road sensor data to help inform the movement of traffic around English ports. This redevelopment was requested by the faster economic indicators team and the Chief Economist.
The redeveloped pipeline features the querying of the Highways England RESTful webTRIS api in parallel using a virtual environment. Additional value beyond the MVP was added with a Shiny UI to add data validation and an automated Rmarkdown report, adding insight on the proportion of site types returning null responses.
DSC GitHub Scrape
In the Summer of 2020 I had been assigned to develop a solution that would ensure the team’s external website reflected the course status on GitHub. As there was much activity in course QA in our backlog, the status of our website would become out of date often.
The pipeline I developed interacts with the GitHub REST API to return all company repositories prefixed with “DSCA_” (capability repositories). In collaboration with the campus faculty, I developed a standardised readme for all courses that required metadata fields could be scraped from.
The resulting table of course repos and metadata is cached on a monthly basis to rds. This is then used to detect changes in course catalogue state. If the number of course repos changes or a course version is incremented, an automated Email using the Gmail API is sent to our internal comms team with a summary of the change and an attached csv file including the updated course catalogue. This routine is scheduled on a monthly basis using cron.
Shiny Applications
These applications are presented in reverse order of publication. While the contexts of the applications vary, they help to illustrate an increasing maturity in Shiny development.
Earth Observation Wildfires
I am currently involved in a project with DSC colleagues in remote sensing wildfires. We all attended the Summer 2021 NASA advanced remote sensing training and have started development in Python & R, identifying & classifying fire risk from satellite rasters.
In order to assist the team’s exploratory work and model evaluation, I have written an app that allows the developer full control over the NASA Fire Information for Resource Management System (FIRMS) API. The application uses authenticated HTTP requests via Web Map Service standard to ingest FIRMS tiles.
The developers can use the various inputs available within the collapsible panes to adjust the query parameters, updating the API response and adjusting the resultant map appearance.
Unifyr
This is an educational application designed to help trainee data scientists in developing their understanding of the different data join functions available within the {dplyr} package. Unifyr allows the learner to select subsets from the well-known gapminder dataset and observe the output of specified join functions.
Click the image to see Unifyr on shinyapps.io, opens in new window.
Google Mobility Data
This Google Mobility Data application was developed at the start of the Covid-19 pandemic using data derived by the optical processing of pdf data publications.
The application allows the user to select specified local authority or NHS bodies in order to view the time series mobility data.
Click the image to see Google mobility data on shinyapps.io, opens in new window.
Welsh School Funding
This application combines 2 open datasets published by Welsh Government: Budgeted educational revenue and outturn expenditure. The available data dimensions may be selected from to plot upon the chart axes by educational phase. Time series data for all available schools and data dimensions may also be viewed upon the second tab.
Click the image to see Welsh school funding data on shinyapps.io, opens in new window.
Common Welsh Place Names
This app was a bit of fun and took very little time. It used some basic language processing and geolocation to plot Welsh location names with common prefixes such as “Cwm” or “Aber” on a map. The application used open data published by the Welsh Language Commissioner who subsequently approached me and were very interested in the project, leading me to sharing the codebase with them.
Click the image to see common Welsh place names on shinyapps.io, opens in new window.
Cardiff Tide Levels
This repo visualises LiDar altitudinal data of Cardiff, openly published by Natural Resources Wales. Cardiff was selected due to comparatively high data quality and population density. The visualisations compare current day high tide altitude with a modelled 2 metre sea rise by the year 2100.
Click the image to see common Cardiff high tide levels on shinyapps.io, opens in new window.
RPubs
Remote Sensing Trees
In 2018 I had been approached by a colleague to discuss the feasibility of using satellite data to help estimate the quantity of woodland stock in a defined rural area. The report documents my exploration work done in this area using open source geospatial frameworks and satellite rasters. The work pointed to a promising avenue of analysis but also indicated limitations in the use of open source landsat imagery. At the time I recommended the procurement of higher resolution remote imagery and verification of tree counts using ground truth observational work.
Click the image to see the counting trees from space exploratory report on RPubs, opens in new window.
Welsh Schools Funding ’18/19
This {flexdashboard} user interface was one of my first pieces of work in application development. The dashboard is an adapted RMarkdown output and can very easily be reproduced with some basic data manipulation and markdown syntax. Furthermore, the product is self-contained and can be Emailed and freely shared, unlike a Shiny application which requires a connection to R and a shiny server.
The dashboard presents Budgeted Education Revenue for financial years 2018/19. An interactive map of geolocated schools in Wales is presented with informative tooltips highlighting the data dimensions. In additional tabs, linear regression models of pupil numbers against delegated budgets for each educational phase are presented.
Click the image to see the Welsh school funding dashboard on RPubs, opens in new window.